</font><p>Scripting in Poco is implemented through PocoScript, an interpreted language created for Poco that focuses on mail processing and handling. Even though it has a narrow focus, PocoScript can act as a conduit between Poco and other applications to implement more sophisticated mail processing, such as mail encryption.</p>
<p>PocoScript is interpreted, high-level language, run directly by the Poco executable. Language syntax is simple, specifically focused at handling e-mail messages. Since the interpreter is part of the main application, to run any scripts you need to have Poco running.</p>
<p>Script is run either on selected messages or on Incoming/Outgoing messages.</p>
<p>PocoScript is not a strongly typed language, but it offers four basic variable types. Variables can have any alphanumeric name, prefixed with the type identifier, listed below:</p>
<p>$ - String variable</p>
<p># - Numeric variable</p>
<p>% - Mail message variable</p>
<p>& - Boolean variable</p>
<p>String types can be assigned out of their type, but the assignment will be successful only if the values are interchangeable. This means that you can assign an integer variable to a string variable at any time, but the reverse will work only when the string contains a true integer. As the script environment was designed to run unattended, badly typed assignments will simply fail.</p>
<p>PocoScript provides several system variables at run time with already assigned values, you can use in your programs:</p>
<b><p>$mailpath</b> = Full path to mailboxes</p>
<b><p>$scriptpath</b> = Full path to scripts</p>
<b><p>$apppath</b> = Full path to application root</p>
<b><p>%message</b> = Contains the message passed to the script to be processed. It is either a selected message that script is run on, or a currently incoming or outgoing message. The %message variable can be modified at run-time, but changes are only passed back to Poco when run on incoming or outgoing mail. When %message is modified while script is running on selected messages, the changes will not affect the original message in the mailbox.</p>
<p>Boolean variables (&var) can be used in several forms, all of which resolve to logical true or false. Value "True", "Yes", "On" or digit "1" all resolve to true, while "False", "No", "Off" or digit "0" resolve to false. Any other assignments to a boolean variable will resolve to true, such as number "42" or string "Friday". Boolean variables are not strongly typed, so you can assign an integer or a string to them. You can apply boolean operators to boolean variables, see Operators section. Boolean variables resolved by the interpreter will always resolve as "1" for true and "0" for false, and as such can be assigned to integer or string variables.</p>
<p>Message variables (%var) consist of message header fields and message body. You can use a set of message commands to operate on message variables. They will allow you to operate on messages as a whole, as well as access individual headers, or save them to a file / mailbox.</p>
<p>When assigning values to string variables, place them in double-quotes to ensure they are fully assigned. If you are assigning a single word, without spaces or separators, you don't need to use quotes.</p>
<p>Most of the operations on the variables are done through built-in commands, including basic addition and subtraction. Exception is the boolean operators. They take form of </p>
<p>value/variable OPERATOR value/variable</p>
<p>These expressions are used mainly in assignment commands, like SET, and in boolean commands, like IF. Following operators can be used:</p>
<p>> Greater than, works for integers and strings. String are compared alphabetically;</p>
<p>< Less than, usage same as >;</p>
<p>= Equals, evaluates true only for equal integers and EXACTLY identical strings;</p>
<p>! Does not equal, usage same as =;</p>
<p>^ Contained within, works practically only on strings. Evaluates true if the first string is contained within the second string.</p>
<p>When applied to strings, all boolean operators are case sensitive. To ignore the case of the compared strings, apply Lowercase or Uppercase commands to the values before the comparison.</p>
<p>PocoScript is fairly adept at handling text files. PocoScript does not support binary files. When opening and saving files, the default directory used is the root directory of your mail folder, or as described above %mailpath. To save outside the default directory, simply use fully qualified file names.</p>
<p>When saving files, the default settings will overwrite any existing files. To change that set AppendToFile to true at the beginning of the script. For instance, if you want to save three messages to a new mailbox call "Stuff", simply run</p>
<p>
AppendToFile true<br>
SaveMessage %m1 Stuff.mbx<br>
SaveMessage %m2 Stuff.mbx<br>
SaveMessage %m3 Stuff.mbx<br>
<p>And that is it. This will create a valid mailbox that you can later open with Poco.</p>
</b><p>Deletes message passed to the script. Practically used only on %message variable; when used on messages instanced by the script, it will only add "D" to the Status header.</p>
</b><p>Sends the prepared message %m via SMTP server setup in the accounts or settings. This command sends immediately, if you want to queue message to be sent later, simple set <i>AppendToFile True </i>and <i>SaveMessage %m Out.mbx</i>.</p>
</b><p>Message %m is opened in Poco to be edited and or possibly sent/queued. EditMessage will not interpret styled text if itÆs in the message, and will extract plain text without formatting tags.</p>
</b><p>Sets "header" of message %m to value of $a. Works only on single-line headers. DonÆt use SetHeader to add message recipients û better support for that is provided by commands AddTo, AddCC and AddBCC.</p>
<p>Appends signature of the current account to the message %m. Signature is parsed at this point for any inserted user tags (see Signatures under Advanced Features in the help file). To change the current account see SetAccount.</p>
<b><a name="AssignBody">AssignBody</a> %m $a</b>
<p>Assigns variable $a as a body of message %m.</p>
<p>It will "quote" or insert quotestring as the beginning of each line of variable $a. quotestring is optional and if left out "greater than" sign is used.</p>
<p>Removes leading quotestring from each line of $a. Reverses QuoteBody. If quotestring is not specified, "greater than" symbol is assumed.</p>
<b><a name="ExtractName">ExtractName</a> $a</b>
<p>Extract person's name from properly formatted e-mail address entry, like "Jane Doe <jdoe@provider.com>". Result overwrites the original value in $a.</p>
<b><a name="ExtractEmail">ExtractEmail</a> $a</b>
<p>Just like the ExtractName, but instead extracts the e-mail address.</p>
<i><p>Following commands read or set current e-mail account information:</p>
<p>All Set commands will assign the value on the right to the variable on the left. Right side can be a value ("John") or a variable ($date). You can assign out of type, just be careful when you use those values later on.</p>
</b><p>All External commands work similar to Set, they assign value to a variable, except they cannot assign a variable to a variable, and the External declarations will show up on the Setup tab of the Scripts. You can only use $userdata1 through $userdata4 and $userfile1 through $userfile4 for variable names if you want Poco to display them to the user. For each $userdata Poco will display an edit field with the description "desc" in the Setup pane of the Filters and Scripts window. Each $userfile will map a button on the same pane to the filename in "value". When user clicks on that button, Poco will launch Notepad with that file loaded. Please take a look at the sample scripts provided for demonstration.</p>
<p>Use InputBox when you want to prompt the user for a value. A window will pop up with question in "desc", and with a default value filled out as "value". User can edit the value, as well as cancel the script at this point. Do not use InputBox in time sensitive operations, as it stops the script execution until user tells it to proceed. The value will be placed in $a.</p>
<p>Inserts string $b into variable $a at the position #n in characters. If #n is larger than the size of $a, the the string is appended to the back of $a. Character positions are one-based, meaning the first character has a position of 1.</p>
<p>Acts identical to InsertString, except it works with lines on multiline variable $a, rather than characters. Line positions are zero-based, meaning the first line has a position of 0.</p>
<b><a name="StringPos">StringPos</a> #n $b $a</b>
<p>Returns in #n the position in characters of string $b inside string $a.</p>
<b><a name="GetLine">GetLine</a> $a #n $b</b>
<p>Places line number #n of multiline variable $b into $a.</p>
<p>Returns true if variable #b/$b/&b contains a number that can be further processed. Otherwise returns false. Due to relaxed variable typing of PocoScript, you can assign a non-integer variable to a number variable like #b. Use this function in those cases.</p>
<p>Similar to IsNumber, but checks for boolean values in the second parameter. Boolean values are 1, 0, true, false, on, off, yes, no. They are not case sensitive. If a value is not boolean, it will still evaluate to true when tested.</p>
<i><p><a name="Other">Other</a></p></i>
<b><a name="GetDate">GetDate</a> $a<p>
GetTime $a</b>
<p>Places current date or time in $a.</p>
<b><a name="SubDays">SubDays</a> #a $b $c</b>
<p>Calculates the difference in days between dates in $b and $c and puts the result in #a. Order of $b and $c is irrelevant - the result is always positive, except when an invalid date is in either $b or $c; the result is then -1.</p>
<p>Use AppendToFile to modify saving to file. When set to true, if file already exists, saved information is appended to the file. When set to false, if file exists it is overwritten with saved information. This variable defaults to false when the script is started.</p>
<b><a name="Execute">Execute</a> file params</b>
<p>Starts an external application specified in "file". The application name has to be either fully qualified or in the windows search path. If you want to pass any parameters to the application, use the optional "params" parameter. Executable name and parameters need to be separated for parameters to be passed correctly. You can also pass non-executable filename - as long as it is registered with Windows correctly, Poco will launch the viewer application on that file. Yes, you can also launch fully qualified URLs, such as http or even mailto.</p>
<p>Works identical to Execute, but unlike Execute, ExecuteAndWait will stop PocoÆs operation and script until the external process is finished. Obviously, caution needs to be exercised when using this command, but it is a great help when running external message processors, such as message encryption.</p>
<p>PlaySound will play a WAV file specified by "file". If you pass the literal "user", PlaySound will instead play the sound defined by the user, in Program Settings. Passing the literal "system" will play the built-in New Mail sound.</p>
<b><a name="MessageBox">MessageBox</a> $a</b>
<p>Shows the informational dialog box with an OK button. Text in $a is used for the message.</p>
<b><a name="Beep">Beep</a></b>
<p>Sounds the Windows system beep, as defined by the user.</p>
<b><a name="Wait">Wait</a> #n</b>
<p>Stops the execution of the script for #n seconds.</p>
<p>Affects the main application window, it will refresh the mailboxes currently showing in Mailboxes window. Use it when you have just created or deleted a mailbox, to keep the application in-sync. If not used, Poco will pick up the new mailboxes on restart, or if user right-clicks and chooses Refresh.</p>
